Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Create a URDF for an Industrial Robot

In this tutorial we will learn to create URDFs for typical industrial manipulators. The URDF XML format is very expressive and allows many different ways of defining the same geometry. We will discuss specific conventions that are meant to:

• simplify the URDF
• create consistencies between robots across vendors
• enable software functionality that relies on these assumptions
• allow the URDF to be included as part of a larger robot work cell (as this is often the case)

Generate STLs from 3D CAD Models

The arm path planning methods that are used by ROS-Industrial are collision aware. In order to take advantage of this capability 3D information about the robot geometry is required.

Prepare CAD Models

Link coordinate systems must be created before exporting STL files from 3D CAD models. The coordinate system present in vendor supplied CAD models are rarely in the desired position. The desired coordinate systems should adhere to the following:

• coincident with the joint nearest to the base of the robot. This placement results in a simple joint transform.
• if possible, oriented such that when the robot is in the zero position, the X-axis points forward and the Z-axis points up.

• NOTE: If using the Solidworks to URDF Exporter plugin for SolidWorks, the coordinate frames and axes of rotation need to be added under the top-level assembly. Tutorials for utilizing the URDF exporter can be found here.

  • all link coordinate frames should be identically-oriented with the X-axis pointing forward and the Z-axis pointing up.

  • if using the URDF Plugin for SolidWorks, after completing the URDF Export Configuration (File->Export as URDF), double check that the Origin_global feature that was created by the URDF exporter is oriented correctly (X-axis forward, Z-axis up) . If it is not correctly oriented, manually correct it by editing the feature, then rerun the URDF Configuration tool to regenerate the URDF file.

Create STLs

The URDF allows for two types of 3D models, visual and collision models.

Visual quality STLs

A visual quality model is used for display purposes only. These models can be highly detailed because they are not used for collision checking. Visual models can be exported directly from a CAD package. Make certain to export binary STLs.

Collision quality STLs

Collision quality models should not be highly detailed. The more detailed these models, the longer it takes to perform collision checks. Collision models should be simple, yet encompass the entire link geometry. It is suggested the convex hulls be created from visual STLs, using a 3D mesh tool such as MeshLab (Filters->Remeshing, Simplification and Reconstruction->Convex Hull).

• NOTE: This tutorial was prepared with MeshLab v1.3.0. The convex hulls created from the original STL in a program such as MeshLab will occassionally result in the surface normals being incorrectly oriented (pointing into the model rather than out of the model). To correct this in MeshLab, simply invert the surface normals (Filters->Normals, Curvatures and Orientation->Invert Faces Orientation). In case of inconsistent normal orientation (mesh shows transparent areas), use Filters->Normals, Curvatures and Orientation->Re-Orient all faces coherently.

Create a URDF for your robot

As you step through the following to create a URDF for your robot, adhere to the following conventions:

• the joint origin is specified by a full transform (see urdf/XML/joint). However, in order to take advantage of some libraries, the joint orientation (roll, pitch, yaw) is limited to a single rotation. That is two of the three orientation angles must remain zero. Because of this, link and/or model transforms may become more complex.

• the joint origins should be oriented with the Z-axis up, and the X-axis forward, when the robot is in the zero position. Assuming this convention was followed when making the STL coordinate frames.

Create a support package for your robot

The convention for the name of a package containing urdf / xacro files along with launch files to bring up the robot controller is <<yourrobot>>_support.

$ catkin_create_pkg <<yourrobot>>_support

Add xacro as dependency to the generated package.xml:

   1 <exec_depend>xacro</exec_depend>

Create a XACRO Macro for your robot

While it is possible to write an explicit URDF for a particular industrial arm, a more general XACRO approach is taken. A XACRO is a type of URDF macro that can be used to generate a URDF. We take this approach because industrial manipulators are often combined with custom end-effectors, requiring a custom URDF. By writing a XACRO that can generate the manipulator portion of the URDF, we provide flexible and extensible library that can be used to generate any custom robot.

See the m10ia_macro.xacro for an example.

For more information on creating an XACRO, see the XACRO tutorials.

Additional/Standard Frames

By convention and in order to match common industrial robot frames, several additional frames should be added to the XACRO

base_link The base_link shall be positioned in the logical base position (oriented by convention, z-axis up, x-axis forward). This frame name is by ROS convention. Typically this frame is the first frame of the robot tied to the first link.

flange The flange shall be the attachment point for an end-effector. As with other robot links it is oriented with the z-axis up (pointing towards the end-effector).

tool0 The tool0 frame (pronounced: 'tool-zero') shall match exactly an all-zeros TCP configuration as defined on the robot controller. For most controllers, this is equal to an unconfigured TCP, which lies on the physical robot's mounting flange.

This transform (between the last robot link and tool0) may be defined in any way (so may consist of all combinations of translations and rotations), as long as it is a fixed joint type in the URDF.

Users are advised to never change flange or tool0, but instead add additional frame(s) as (a) child(ren) of flange.

The following snippet shows an example definition:

   1 <link name="${prefix}tool0" />
   2 
   3 <joint name="${prefix}link_6-tool0" type="fixed">
   4   <parent link="${prefix}link_6" />
   5   <child link="${prefix}tool0" />
   6   <origin xyz="0 0 0" rpy="0 0 0" />
   7 </joint>

base The base frame shall match exactly the base defined by the robot controller. Its purpose is to allow users to transform points into the Cartesian base frame of the robot. Examples of base frames are the World Frame on Fanuc controllers and $ROBROOT for KUKA.

The transform between base and base_link can be defined in any way, as long as the transform is fixed between the two (i.e. not across a movable joint). The preference is for base to be defined relative to base_link. It does not have to be part of the main kinematic chain.

The following snippet shows an example base definition:

   1 <link name="${prefix}base" />
   2 
   3 <joint name="${prefix}base_link-base" type="fixed">
   4   <parent link="${prefix}base_link" />
   5   <child link="${prefix}base" />
   6   <origin xyz="0 0 0" rpy="0 0 0" />
   7 </joint>

Generate a URDF for your robot

In order to generate a URDF for your robot, another XACRO (a "top-level" XACRO) must be written to call the XACRO macro written in the previous section. See m10ia.xacro for an example.

Note that URDFs are not composible - meaning that you cannot (easily) combine them with other models as you can with XACROs. Most tools that consume URDF in ROS are capable of loading XACRO directly, so there is typically no need to manually convert them to URDFs.

Converting like below can be a good check to see whether your XACRO is formatted correctly though, so it could still be useful.

To generate the URDF and check the result (Groovy and older):

$ rosrun xacro xacro.py -o <<urdf_file>> <<xacro_file>>
$ rosrun urdf_parser check_urdf <<urdf_file>>

To generate the URDF and check the result (Hydro and newer):

$ rosrun xacro xacro.py -o <<urdf_file>> <<xacro_file>>
$ check_urdf <<urdf_file>>

If successful, the commands above will generate a URDF of your industrial manipulator. As an example, see the m10ia.urdf.

Generate a URDF for your robot and end-effector (Optional)

This section is meant to demonstrate why a XACRO is used instead of directly writing the URDF. In the case where an end-effector is added to the robot, the XACRO comes in handy.

See the following robot + end-effector example.

Verify your URDF

It is very important that the information within the URDF is accurate. Specifically, the joint limits and orientations will used in the following steps and must be correct. To visualize your robot run the following:

$ roslaunch urdf_tutorial display.launch model:=<<urdf_file>> gui:=True

Use the GUI sliders to verify the joint orientation (i.e. plus/minus moves the actual robot). Also verify that the joint limits match.